refactor(cli): scope --connector to TensorRT-LLM - #12611

# Plan — remove the deprecated `--connector` CLI flag

Route: implementation
Template: change-build-deploy-measure
Engine: vllm

No `Disposition:` line applies: no merged PR removes the flag on `main`, and the
flag is still registered and still parsed at HEAD. No `Review request:` line
applies either — PR #12568 is merged and terminal, PR #12581 is an unrelated
two-line docs fix about `--is-prefill-worker` on somebody else's branch, and
there is no open request competing for this cleanup (see Discovery).

## User intent

The caller wants the deprecated `--connector` flag gone from the repository —
"remove any `--connector` logic at all" — as a follow-up to the merged docs PR
#12568. The Slack thread that produced this work item is explicit that the flag
"was deprecated and removed awhile ago and we should be able to just remove it."

Read literally and repository-wide, that instruction is broader than what is
safe. Discovery establishes that `--connector` is **not** uniformly dead: it is
inert for vLLM (a rejection path that only raises errors) but **live and
load-bearing for TensorRT-LLM**, where `--connector kvbm` is the supported way
to turn on the KVBM TRT-LLM integration. So the honest reading of the intent —
and what this plan implements — is: remove the flag's vLLM-side legacy
machinery and every stale mention of it in docs, recipes, and comments, and
narrow the flag's remaining registration so it is owned by TRT-LLM alone rather
than advertised on the shared runtime surface that vLLM, SGLang, tokenspeed,
and omni all inherit. Deleting the TRT-LLM path outright would break a shipping
feature, so this plan does not do that; it says so plainly and leaves that as a
follow-up decision for the maintainer who asked.

## Non-goals

- **Not** removing `--connector kvbm` support from the TensorRT-LLM backend.
  That is live behavior with tests, a KVBM code path, and a snapshot guard.
  Deleting it is a functional regression, not a cleanup.
- **Not** touching NIXL connectors, `dynamo.nixl_connect.Connector`, vLLM
  upstream `KVConnector` / `NixlConnector` / `PdConnector` / `DynamoConnector`,
  `--kv-transfer-config`, `kv_connector_module_path`, the KVBM Rust connector
  crates, the multimodal media connector, or the Planner's Kubernetes/virtual
  "connectors". These share a word, not a concept.
- **Not** revising the deprecation ledger entry in
  `docs/fern/pages/reference/general/releases/deprecations.mdx`. A release-notes
  record of a removed flag is supposed to keep naming the flag; erasing it
  destroys the migration guidance users still need.
- **Not** rewriting or re-litigating PR #12568's docs prose beyond deleting the
  `--connector` error-message paragraph that this change makes untrue.
- **Not** a performance change. This work item makes no perf claim, so Recipe 10
  is out of scope.

## Discovery

Everything below was read or run against the read-only checkout at
`/home/sandbox/workspace/wi-20260803T205823Z-12568/repo` on branch `main`,
HEAD `27e6820b5 docs(vllm): correct worker-role flags and document
--kv-transfer-config (#12568)`.

### Inventory: 76 raw hits, four distinct concepts

`grep -rn -- "--connector"` over the checkout returns 76 lines. Classified:

**Bucket A — the deprecated CLI flag itself (IN SCOPE).**

`components/src/dynamo/common/configuration/groups/runtime_args.py:174-181`
registers it on the **shared** runtime ArgGroup that every backend inherits:

```python
add_argument(
    g,
    flag_name="--connector",
    env_var="DYN_CONNECTOR",
    default=[],
    help="[Deprecated for vLLM] Use --kv-transfer-config instead. For TRT-LLM, options: nixl, lmcache, kvbm, null, none.",
    nargs="*",
)
```

with the backing field at line 35, `connector: list[str]`, on
`DynamoRuntimeConfig`.

`components/src/dynamo/vllm/args.py` holds the vLLM-side legacy machinery:
line 214 calls `_reject_connector_flag(dynamo_config)`; line 234 does the dead
`dynamo_config.connector = []  # type: ignore[assignment]`; lines 474-513 are
`_connector_to_kv_transfer_json()`, whose entire docstring says it is
"Used in error messages to help users migrate"; lines 516-563 are
`_reject_connector_flag()`. Also line 226, inside an *unrelated* prefill
validation error, opens with a stale sentence about the flag:

```python
raise ValueError(
    "--connector is deprecated and the default is no longer nixl. "
    "When using --disaggregation-mode prefill, you must explicitly "
    "provide --kv-transfer-config. Example:\n"
    ...
```

**Bucket B — the LIVE TRT-LLM path (OUT OF SCOPE for deletion; in scope for
re-homing only).** This is the decisive finding and it contradicts the premise
that the flag is dead everywhere. `components/src/dynamo/trtllm/args.py:35`
defines `VALID_TRTLLM_CONNECTORS = {"none", "kvbm"}`; lines 43-73 validate the
value and expose `has_connector()`; and
`components/src/dynamo/trtllm/workers/llm_worker.py:110-123` branches on it to
build real engine configuration:

```python
def build_kv_connector_config(config: Config):
    if config.connector:
        if config.connector[0] == "kvbm":
            return KvCacheConnectorConfig(
                connector_module="kvbm.trtllm_integration.connector",
                connector_scheduler_class="DynamoKVBMConnectorLeader",
                connector_worker_class="DynamoKVBMConnectorWorker",
            )
```

plus `llm_worker.py:262` (`if config.has_connector("kvbm"):
kv_cache_config.enable_partial_reuse = False`) and
`components/src/dynamo/trtllm/snapshot.py:191`, which refuses snapshotting when
`--connector kvbm` is set. `tests/kvbm_integration/test_determinism_disagg.py:250`
launches `python -m dynamo.trtllm ... --connector kvbm` for real. So: **the flag
still has live behavioral logic**, but only for TRT-LLM. For vLLM it is
**already inert** — the only thing it can do is raise.

**Bucket C — documentation (IN SCOPE, selectively).**
`docs/fern/pages/reference/components/runtime-configuration.mdx:123-127` is a
`<ParamField path="--connector">` that documents the shared flag as generally
available. `docs/fern/pages/reference/backends/vllm-configuration.mdx:94-98` is
the paragraph #12568 added describing exactly which `ValueError` each rejected
value produces — prose that becomes false the moment the rejection path is
deleted. `docs/fern/pages/reference/general/releases/deprecations.mdx:237-239`
is the historical ledger entry citing PR #6450 — **leave it alone** (see
Non-goals). `recipes/nemotron-3-super-fp8/README.md:143` and
`recipes/nemotron-3-super-fp8/vllm/agg/deploy.yaml:8,105-106` are 0.9.1
back-compat notes telling users to add `--connector none` on an old release.

**Bucket D — unrelated `connector` concepts (DO NOT TOUCH).** The bulk of the
76 hits, and the main regression risk. All 40-odd `--connector` matches under
`docs/fern/assets/img/disagg-*.svg` are **CSS custom properties** —
`--connector: #CBD5E1;`, `stroke="var(--connector)"` — arrowhead colors in
diagrams. They match the grep only because CSS variables also start with `--`.
`lib/llm/src/block_manager/config.rs:213` is a Rust doc comment that mentions
`--connector kvbm` while describing the KVBM consolidator; since the TRT-LLM
flag survives, that comment stays accurate and stays put. Separately,
`components/src/dynamo/trtllm/request_handlers/handler_base.py:291`
(`self.connector = config.connector`) is a **NIXL** connector, not the CLI list:
`handler_base.py:242` declares `connector: Optional[Connector] = None` against
`from dynamo.nixl_connect import Connector` (line 44), and it is used for
multimodal embedding RDMA in `encode_helper.py` (`connector.begin_read`,
`connector.create_readable`). Same attribute name, different object, different
subsystem. Touching it would break multimodal encode.

### Blast radius of removing the shared field

`grep -rn "DynamoRuntimeArgGroup\|DynamoRuntimeConfig"` shows five consumers of
the shared group: `vllm/args.py`, `trtllm/args.py`, `sglang/args.py`,
`tokenspeed/args.py`, `vllm/omni/args.py`, plus
`common/snapshot/restore_context.py:109`, which re-parses runtime args
standalone. Of these, `grep -n "connector"` over `sglang/args.py`,
`tokenspeed/args.py`, and `vllm/omni/args.py` returns **nothing** — they inherit
the flag and ignore it entirely. `common/backend/worker.py:151-200`
(`from_runtime_config`) enumerates the runtime fields it forwards and
`connector` is **not** among them. So moving the flag out of the shared group
onto TRT-LLM breaks no other backend. `ConfigBase.from_cli_args`
(`common/configuration/config_base.py:14-37`) copies argparse values by name and
then materializes annotated class defaults, so a field that no longer exists in
the shared annotations simply stops being set — no `KeyError`, no positional
coupling. `grep` for config-dump goldens or snapshot fixtures pinning a
`"connector"` key found none, so no golden file needs regenerating.

### Related PRs and history (host-verified)

`gh auth status` reports logged in as `glamr-agent`, so host queries below are
verified, not guessed.

- **#12568** — `gh pr view` confirms `"state":"MERGED"`, `mergedAt
  2026-08-03T20:58:16Z`, and a single file changed
  (`docs/fern/pages/reference/backends/vllm-configuration.mdx`, +28/-15). It is
  present at HEAD. It is docs-only and did **not** remove any flag logic, which
  is precisely why this follow-up exists. It is terminal — not a babysitting
  target.
- **#6450** — `feat: remove --connector flag for vLLM backend (LLM-90)`,
  **MERGED**. This is the change the deprecations ledger cites and the one that
  made the vLLM path inert. It removed vLLM's *use* of the flag but left the
  shared registration and the rejection scaffolding standing.
- **#6513** — same title, **CLOSED** unmerged; a superseded duplicate of #6450.
  Not a live approach to defer to.
- **#12581** — `docs(cli): correct removed vLLM prefill-worker flag reference`,
  **OPEN**, branch `dagil-nvidia/docs-dyn3726-flag-removal`. This is the PR from
  the Slack thread. It is about `--is-prefill-worker`, not `--connector`, and it
  does not touch any file in this plan's scope. Not a competitor; no reason to
  defer to it.
- Searches `gh pr list --state all --search` for `"remove connector flag"`,
  `"DYN_CONNECTOR"`, `"connector deprecat"`, and `"12568"` surfaced **no open
  PR** removing this flag. The many open `connector`-titled PRs (#8014
  kvbm-connector, #11219 NixlPushConnector, #7624 PegaFlow connector, #11350 TLS
  connector stack, #8437 planner connector) are all Bucket-D concepts.
- **Unverified:** `git log -S "--connector"` and `git log -S
  "_reject_connector_flag"` both exceeded their time budget on this checkout
  (git auto-gc repacking; the searches were terminated at 2m and 9m
  respectively). I therefore did **not** independently confirm the introducing
  commit for `_reject_connector_flag` from local history. Path-scoped history
  did run: `git log --oneline -12 -- components/src/dynamo/vllm/args.py` and the
  same for `runtime_args.py` show no `--connector`-related commit in the last
  twelve touches of either file, which is consistent with #6450 being old. The
  provider metadata above (#6450 MERGED) is the load-bearing evidence for when
  the flag was removed; the local `-S` archaeology is recorded here as
  unverified rather than asserted.

### Existing test coverage — RUN / IGNORE verdicts

Per `learnings/no-tautological-tests.md` and
`learnings/discovery-survey-before-planning.md`, so the printer does not write
duplicates:

- `components/src/dynamo/vllm/tests/test_vllm_unit.py:231-252` —
  `test_connector_nixl_raises_error_with_migration_hint`,
  `test_connector_none_raises_error`,
  `test_env_var_dyn_connector_raises_error`. **IGNORE — these must be
  DELETED**, not run. They exist solely to assert the rejection messages this
  change removes. Keeping them guarantees a red suite.
- `components/src/dynamo/vllm/tests/test_vllm_unit.py:289-298` —
  `test_connector_to_kv_transfer_json_single` / `_multi`, which import
  `_connector_to_kv_transfer_json` at line 23. **IGNORE — DELETE**, together
  with the import; the function under test is being deleted.
- `components/src/dynamo/trtllm/tests/test_trtllm_unit.py:229-248` —
  `test_config_has_connector` and the "at most one connector entry" raises-test.
  **RUN, unmodified.** These cover the live TRT-LLM behavior this change must
  not regress; they are the regression net for the re-homing. `pytestmark` is at
  line 40 and the module imports `torch`, so it needs the validation venv.
- `components/src/dynamo/trtllm/tests/test_trtllm_snapshot.py:43,109` — stubs
  `has_connector` and asserts the `--connector kvbm` snapshot rejection.
  **RUN, unmodified.**
- `components/src/dynamo/trtllm/tests/utils.py:31` — `config.connector = None`
  on a MagicMock for the NIXL-connector handler fixture (Bucket D). **IGNORE —
  do not touch.**
- `tests/kvbm_integration/test_determinism_disagg.py:250` — passes `--connector
  kvbm` to `dynamo.trtllm`. **IGNORE (leave as-is)**; it exercises the surviving
  TRT-LLM path and requires multi-GPU KVBM integration hardware this sandbox
  does not have. It is listed here so the printer does not "clean it up" and
  break a real integration test.

No new behavioral test is warranted for the vLLM side: after this change there
is no vLLM `--connector` behavior left to assert. A test that `--connector` is
absent from `python -m dynamo.vllm --help` would be a config mirror. The real
proof is the negative runtime check described under Validation.

## Chosen approach

Delete vLLM's legacy `--connector` machinery outright, and move the flag's
registration off the shared runtime ArgGroup and onto the TRT-LLM backend group
that is its only real consumer. After this change, `--connector` exists exactly
where it is implemented and nowhere else: `python -m dynamo.vllm --connector
nixl` fails with argparse's standard `unrecognized arguments` error instead of a
bespoke `ValueError`, and `python -m dynamo.trtllm --connector kvbm` keeps
working unchanged.

This is the smallest change that satisfies "remove all `--connector` logic"
without regressing a shipping feature. The bespoke rejection path was itself
transitional scaffolding: an error message whose only job was to migrate users
off a flag removed in #6450, long enough ago that the deprecations ledger
already lists it under a red "Removed" badge. Argparse's own error is now the
correct behavior for an unknown flag.

### Files to EDIT

1. `components/src/dynamo/common/configuration/groups/runtime_args.py`
   - Delete the `--connector` / `DYN_CONNECTOR` `add_argument(...)` block
     (lines 174-181).
   - Delete `connector: list[str]` from `DynamoRuntimeConfig` (line 35).

2. `components/src/dynamo/trtllm/backend_args.py`
   - Add the `--connector` / `DYN_CONNECTOR` registration to
     `DynamoTrtllmArgGroup.add_arguments`, using the same `add_argument(...)`
     helper and `nargs="*"`, `default=[]`. Rewrite the help text to drop the
     now-meaningless "[Deprecated for vLLM]" preamble and describe only what
     TRT-LLM actually accepts — `none` and `kvbm`, per
     `VALID_TRTLLM_CONNECTORS`. (The old help string advertised `nixl` and
     `lmcache`, which `trtllm/args.py:56` rejects; fixing that is part of
     removing stale flag documentation.)
   - Declare `connector: list[str]` on `DynamoTrtllmConfig` so the field has a
     home.

3. `components/src/dynamo/trtllm/args.py`
   - Keep `VALID_TRTLLM_CONNECTORS`, `Config.validate()`'s connector block, and
     `has_connector()` exactly as they are.
   - The `connector: list[str]  # Redeclare for mypy (inherited from
     DynamoRuntimeConfig)` at line 41 either loses its stale comment or is
     dropped once the field is declared on `DynamoTrtllmConfig`; printer's
     judgment, as long as mypy stays clean.

4. `components/src/dynamo/vllm/args.py`
   - Delete the `_reject_connector_flag(dynamo_config)` call (line 214) and its
     comment (line 213).
   - Delete `dynamo_config.connector = []` and its comment (lines 233-234).
   - Delete `_connector_to_kv_transfer_json()` (lines 474-513) and
     `_reject_connector_flag()` (lines 516-563) entirely.
   - Rewrite the prefill error at lines 225-231 to drop the leading
     "`--connector` is deprecated and the default is no longer nixl.` " sentence,
     preserving the actionable remainder: that `--disaggregation-mode prefill`
     requires an explicit `--kv-transfer-config`, with the same example JSON.
     **This message is asserted by the vLLM prefill test and documented in
     `vllm-configuration.mdx`; keep the surviving sentence verbatim so both stay
     true.**
   - Remove the now-unused `json` / `os` imports **only if** nothing else in the
     module uses them (verify before deleting; `os` is very likely still used).

5. `components/src/dynamo/vllm/tests/test_vllm_unit.py`
   - Delete the three tests at lines 231-252 and the two at lines 289-298, plus
     the `_connector_to_kv_transfer_json` import at line 23 and the
     `# --connector removal tests` banner comment.

6. `docs/fern/pages/reference/components/runtime-configuration.mdx`
   - Delete the `<ParamField path="--connector" ...>` block (lines 123-127).
     This page documents the shared runtime surface; the flag is no longer part
     of it. If the printer judges that TRT-LLM's flag deserves a home in the
     docs, add it to the TRT-LLM backend reference page instead — but do not
     leave it advertised as a universal runtime option. Follow
     `docs/fern/AGENTS.md`: Fern frontmatter, no body `# H1`, backend casing.

7. `docs/fern/pages/reference/backends/vllm-configuration.mdx`
   - Delete the paragraph and bullet list at lines 94-98 describing the
     `ValueError` messages produced by `--connector` / `DYN_CONNECTOR`. Those
     messages no longer exist; leaving them is worse than the bug #12568 fixed.
     Keep everything else #12568 added, in particular the
     `--kv-transfer-config` guidance immediately above it.

8. `recipes/nemotron-3-super-fp8/README.md` (line 143) and
   `recipes/nemotron-3-super-fp8/vllm/agg/deploy.yaml` (lines 8, 105-106)
   - Remove the `--connector none` 0.9.1 back-compat notes. They instruct users
     to pass a flag that no longer parses, and the surrounding comments already
     say it is "no longer needed in 1.0". Delete the note lines and leave the
     rest of the 0.9.1 compatibility guidance intact.

### Files to DELETE

None. No file exists solely to serve this flag.

### DO NOT TOUCH — the regression guard

The following all contain the string `connector` and none of them are this
flag. Changing any of them is a regression, not a cleanup:

- **All `docs/fern/assets/img/disagg-*.svg`** — `--connector` there is a CSS
  custom property for arrow stroke color (`--connector: #CBD5E1`,
  `var(--connector)`, `marker-end="url(#arrow-var--connector)"`). Roughly 40 of
  the 76 grep hits. Editing them silently breaks four architecture diagrams.
- **`docs/fern/pages/reference/general/releases/deprecations.mdx:237-239`** —
  the historical "Connector Flag Replaced (#6450)" ledger entry and its
  migration instructions. Release history must keep naming removed flags.
- **The entire TRT-LLM KVBM path**: `VALID_TRTLLM_CONNECTORS`,
  `Config.has_connector`, `trtllm/workers/llm_worker.py:110-123` and `:262`,
  `trtllm/snapshot.py:191`, `trtllm/tests/test_trtllm_unit.py:229-248`,
  `trtllm/tests/test_trtllm_snapshot.py:43,109`, and
  `tests/kvbm_integration/test_determinism_disagg.py:250`.
- **`--kv-transfer-config` and every `kv_connector*` key**: `_uses_nixl_connector`,
  `_uses_dynamo_connector` (`vllm/args.py:431-471`),
  `vllm/kv_connector_protocols.py`, `vllm/main.py:578-592`,
  `vllm/handlers.py`, and every YAML/shell literal containing
  `"kv_connector":"NixlConnector"` / `"PdConnector"` / `"DynamoConnector"` /
  `"kv_connector_module_path":"kvbm.vllm_integration.connector"` across
  `examples/backends/vllm/**`, `recipes/qwen3-32b/vllm/agg-kvbm/deploy.yaml`,
  and `tests/kvbm_integration/**`. This is the machinery #12568 documented as
  the *replacement*; damaging it defeats the purpose of the follow-up.
- **NIXL connectors**: `dynamo.nixl_connect.Connector` and every
  `self.connector` bound to it — `trtllm/request_handlers/handler_base.py:242,291`,
  `trtllm/request_handlers/handlers.py:83,128,132,167`,
  `trtllm/encode_helper.py`, `trtllm/tests/utils.py:31`,
  `common/multimodal/embedding_transfer.py`, `common/utils/media_nixl.py`,
  `vllm/omni/connectors/nixl_connector.py`, and
  `sglang/request_handlers/llm/decode_handler.py:195`.
- **All Rust**: `lib/llm/src/block_manager/config.rs:213` (a doc comment that
  stays accurate because the TRT-LLM flag survives),
  `lib/bindings/kvbm/src/block_manager/vllm/connector/**`, and
  `lib/runtime/src/transports/etcd.rs` (`self.connector` is an etcd client
  connector). No Rust file is edited by this change.
- **Planner / Kubernetes / operator**: `components/src/dynamo/planner/connectors/**`,
  `global_planner/kubernetes_capacity_manager.py`, and
  `deploy/operator/internal/dynamo/backend_vllm_test.go:75-80` (Go test
  asserting `--kv-transfer-config` passthrough).
- **Multimodal media/embedding-cache connectors**:
  `common/multimodal/media_connector.py`,
  `vllm/multimodal_utils/multimodal_embedding_cache_connector.py`, and their
  tests.

Per `learnings/format-changed-only.md`, format only the touched files — no
repo-wide `ruff format` or bare `cargo fmt`. Per
`learnings/never-push-to-upstream.md`, the printer and validator push nothing;
only the publisher pushes, and only to the configured destination on branch
`docs/remove-connector-flag--bb15f14dece7` against base `main`.

Note for the printer's `change.md`: state explicitly that TRT-LLM's
`--connector` survives and why, so the reviewer and the PR description can carry
that caveat back to the maintainer who asked for total removal. The PR
description should say: vLLM-side logic and stale docs removed; TRT-LLM
`--connector {none,kvbm}` retained and re-homed onto the TRT-LLM arg group;
removing it too would delete the KVBM TRT-LLM integration entry point and needs
a separate decision.

## Rejected alternatives

**Delete `--connector` everywhere, including TRT-LLM.** This is the literal
reading of the request and it loses on evidence.
`build_kv_connector_config()` in `trtllm/workers/llm_worker.py` is the only
thing that wires `KvCacheConnectorConfig(connector_module=
"kvbm.trtllm_integration.connector", ...)`, and `test_determinism_disagg.py`
launches with it. Removing it silently disables KVBM for TRT-LLM users with no
migration path — TRT-LLM has no `--kv-transfer-config` equivalent to migrate to.
The Slack instruction was written about the vLLM flag (the thread is a vLLM docs
thread, following a vLLM docs PR); applying it to TRT-LLM would be
over-literal compliance that breaks a feature. Recorded and surfaced rather than
silently performed.

**Leave the flag registered on the shared group and only delete the vLLM
rejection helpers.** Smaller diff, but it leaves `--connector` advertised in
`python -m dynamo.vllm --help`, in `python -m dynamo.sglang --help`, and in the
shared runtime-configuration reference page — for four backends that ignore it.
That is exactly the stale surface the caller is asking to clean up, and it
would leave the docs page this change is meant to fix still describing a
universal flag. Re-homing is barely larger and actually resolves the complaint.

**Keep the vLLM `ValueError` as a friendlier error than argparse's.** The
migration window closed with #6450; the deprecations ledger already carries the
migration text under a red "Removed" badge, and #12568 refreshed the
`--kv-transfer-config` guidance. Keeping bespoke rejection code for a flag
removed that long ago is the definition of what the caller asked to delete.

**Required vs. optional parameter shape.** This change removes a field rather
than adding a parameter, so the usual "required parameter forces every caller to
change" tradeoff inverts: the risk is a *reader* of `config.connector` that I
did not find. I mitigated it by enumerating consumers directly
(`grep -rn "DynamoRuntimeArgGroup\|DynamoRuntimeConfig"`, `grep -rn
"\.connector\b\|has_connector\|DYN_CONNECTOR"`) and confirming SGLang,
tokenspeed, omni, and `common/backend/worker.py::from_runtime_config` never
read it. Validation closes the loop empirically rather than trusting the grep.

## Validation strategy

The functional claim is narrow and testable: **after this change, the vLLM
backend still parses its arguments and starts and serves, `--kv-transfer-config`
still works exactly as #12568 documented, TRT-LLM's `--connector kvbm` still
parses and still selects the KVBM connector config, and `--connector` is gone
from the vLLM surface.** There is no performance claim, so no baseline/treatment
measurement and no Recipe 10.

**Recipe 00 (`00-dynamo-editable-install`)** — mandatory preflight. Every test
and smoke below imports `dynamo.*`, and `runtime_args.py` — a file this change
edits — is on the import path of every backend. Record the idempotent
confirmation and the `import dynamo, dynamo._core` sanity check.

**Recipe 01 (`01-python-lint`)** — `py_compile` on each changed `.py` plus
`pre-commit run --files <changed files>`. This change touches four `.mdx`/`.md`
docs files and two recipe/YAML files alongside the Python, and the docs subset
is deterministically enforced pre-merge per `AGENTS.md`. Lint is the right proof
for the docs half. Files only, never `--all-files`-style reformatting.

**Recipe 03 (`03-python-unit-tests-mocker`)** — the core regression net, and the
one that catches a missed `config.connector` reader. Run, at minimum:
`components/src/dynamo/trtllm/tests/test_trtllm_unit.py` and
`test_trtllm_snapshot.py` (RUN verdicts above — these must stay green,
unmodified, proving the live TRT-LLM path survived re-homing);
`components/src/dynamo/vllm/tests/test_vllm_unit.py` (proving the vLLM parser
still works with the deleted tests removed and nothing else broken); and the
SGLang and omni arg-parsing tests, which exercise backends that inherited the
now-deleted shared field and must keep parsing. Green TRT-LLM connector tests
against edited registration code is real evidence, not a tautology: those tests
predate this change and assert behavior, not configuration.

**Recipe 04 (`04-python-runtime-lint`)** — runtime-code lint over the touched
runtime modules (`runtime_args.py`, `vllm/args.py`, `trtllm/args.py`,
`trtllm/backend_args.py`). Cheap, and it catches the dead-import case flagged in
the edit list (a leftover `json`/`os` import after the helper deletions).

**Recipe 07 (`07-agg-smoke`)** — the run that beats a read, and the one this
sandbox exists to provide. The A100-80GB and vLLM 0.22.0 are present, the engine
matches `Engine: vllm`, and the change edits vLLM's argument-parsing path, so a
static claim that "the worker still starts" would be unacceptable. Recipe 07
must establish three things in the same session:

1. **Positive:** a small model (e.g. `Qwen/Qwen3-0.6B`) aggregate smoke —
   `python -m dynamo.vllm` starts, registers, and serves a completion. This
   proves argument parsing survived removal of a field from the shared
   `DynamoRuntimeConfig`, which is the single highest-risk edit.
2. **Negative:** `python -m dynamo.vllm --model Qwen/Qwen3-0.6B --connector nixl`
   exits non-zero with argparse's `unrecognized arguments: --connector`. This is
   the removal proof — that the flag is genuinely gone from the vLLM surface,
   not merely silently accepted-and-ignored (which would be a worse outcome than
   today's `ValueError`). Capture the exact stderr.
3. **Collateral-damage check for #12568:** start the worker with
   `--kv-transfer-config '{"kv_connector":"NixlConnector","kv_role":"kv_both"}'`
   and confirm it is accepted and reaches the same healthy serving state. #12568
   exists to document that path; this follow-up must not damage it. A cheaper
   variant — confirming that `--disaggregation-mode prefill` *without*
   `--kv-transfer-config` still raises the (now reworded) `ValueError` — should
   be captured in the same run via Recipe 03, since that error string is one this
   change edits.

Recipe 08 is **not** nominated: this change alters no KV-transfer, routing, or
NIXL code path — the do-not-touch list is precisely those areas — so a
prefill/decode pair would exercise nothing the aggregate smoke plus the
`--kv-transfer-config` acceptance check does not already cover, at materially
higher cost. Recipe 09 is not nominated: the connector-adjacent GPU tests
(`tests/kvbm_integration/**`) are TRT-LLM/KVBM multi-GPU integration tests
outside this change's blast radius and outside this sandbox's single-A100
budget. Recipe 02 is not nominated: no `.rs` file is edited (the sole Rust hit
is a doc comment on the do-not-touch list). Recipes 11 and 12 are not
nominated: nothing under `deploy/operator/**` or `deploy/helm/**` is touched.
Recipe 06 is **N/A** — no Dockerfile changes, and this sandbox has no Docker
socket, so nominating it would be indefensible. Recipe 05 is deliberately
**not** nominated: every claim here is executable in this sandbox, and per the
recipe index, inspection is only for what genuinely cannot be run.

```validation-recipes
00-dynamo-editable-install
01-python-lint
03-python-unit-tests-mocker
04-python-runtime-lint
07-agg-smoke
```

## Required deliverables

- `plan.md` — this file.
- `change.md` and `change.diff` from the printer, implementing the file-by-file
  scope above. `change.md` must state explicitly that TRT-LLM's `--connector`
  is retained and why, and must note that no new behavioral test is added on the
  vLLM side because there is no surviving vLLM behavior to assert (per
  `learnings/no-tautological-tests.md`).
- `change-validation.md` from the validator: every recipe stem in the fenced
  block run through the recorder into `validation/registry.jsonl`, including the
  Recipe 07 positive smoke, the negative `--connector` rejection with captured
  stderr, and the `--kv-transfer-config` acceptance check. Ends with exactly
  `## Verdict: pass`, `fail`, or `blocked`.
- `review.md` from the reviewer, ending with exactly `## Assessment: sound` or
  `needs_changes`. The reviewer should specifically confirm no do-not-touch path
  appears in `change.diff` — in particular that no `docs/fern/assets/img/*.svg`,
  no `kv_connector*` literal, no NIXL `Connector` usage, and no TRT-LLM KVBM
  code path was modified.
- Publication by the publisher alone: branch
  `docs/remove-connector-flag--bb15f14dece7` against base `main`, PR opened
  ready for review with `## Summary` and `## Validation` sections, referencing
  the follow-up relationship to #12568 and flagging the retained TRT-LLM flag
  under `## Notes`.

# change.md — remove `--connector` from the shared runtime arg group

## Commit

- **SHA:** `06a1058ba6d9d979f0fc779ce436ec4aa9afa508`
- **Branch:** `docs/remove-connector-flag--bb15f14dece7` (branched from `main` @ `27e6820b580609f50ce9625f1da540f44223caa2`)
- **Title:** `refactor(cli): re-home --connector to TRT-LLM and drop vLLM rejection path`
- **Sign-off:** present (`Signed-off-by: svc-glamr@nvidia.com <svc-glamr@nvidia.com>`), committed with `git commit --signoff`
- **Pushed:** no. Nothing was pushed to origin or anywhere else.
- **Diff stat:** 9 files changed, 10 insertions(+), 169 deletions(-)

I chose `refactor(cli):` over `chore(cli):` because this is a behavioural
re-shaping of the CLI surface (a flag moves scope and a rejection path changes
from a hand-written `ValueError` to argparse's own error), not housekeeping.

## Files changed

| File | +/- |
|---|---|
| `components/src/dynamo/common/configuration/groups/runtime_args.py` | -9 |
| `components/src/dynamo/trtllm/backend_args.py` | +10 |
| `components/src/dynamo/trtllm/args.py` | -1 |
| `components/src/dynamo/vllm/args.py` | -100 |
| `components/src/dynamo/vllm/tests/test_vllm_unit.py` | -42 |
| `docs/fern/pages/reference/components/runtime-configuration.mdx` | -6 |
| `docs/fern/pages/reference/backends/vllm-configuration.mdx` | -6 |
| `recipes/nemotron-3-super-fp8/README.md` | -1 |
| `recipes/nemotron-3-super-fp8/vllm/agg/deploy.yaml` | -4 |

### Per-file summary

1. **`components/src/dynamo/common/configuration/groups/runtime_args.py`** —
   removed the `--connector` / `DYN_CONNECTOR` registration from
   `DynamoRuntimeArgGroup.add_arguments` and the `connector: list[str]`
   annotation from `DynamoRuntimeConfig`. This is the load-bearing edit: the
   flag is no longer inherited by every backend, only by TRT-LLM.

2. **`components/src/dynamo/trtllm/backend_args.py`** — added the same
   `add_argument(..., flag_name="--connector", env_var="DYN_CONNECTOR",
   default=[], nargs="*")` block to `DynamoTrtllmArgGroup.add_arguments` and the
   `connector: list[str]` annotation to `DynamoTrtllmConfig`. The help text was
   rewritten to describe only what `VALID_TRTLLM_CONNECTORS` actually accepts
   (`kvbm`, `none`); the old shared text advertised `nixl`, `lmcache` and `null`,
   which TRT-LLM rejects.

3. **`components/src/dynamo/trtllm/args.py`** — deleted the one-line
   `connector: list[str]  # Redeclare for mypy (inherited from
   DynamoRuntimeConfig)` from `class Config(DynamoRuntimeConfig,
   DynamoTrtllmConfig)`. The comment was now false, and the annotation is
   redundant because `Config` inherits it through `DynamoTrtllmConfig`. All
   TRT-LLM connector *logic* (`VALID_TRTLLM_CONNECTORS`, the `validate()`
   connector block, `has_connector()`) is untouched.

4. **`components/src/dynamo/vllm/args.py`** — deleted
   `_reject_connector_flag()` and `_connector_to_kv_transfer_json()`, the call
   to the former in `update_dynamo_config_with_engine`, and the
   `dynamo_config.connector = []` reset. Removed the now-unused `import json`.
   The prefill guard lost only its first sentence ("`--connector` is deprecated
   and the default is no longer nixl."); the rest of that message is byte-for-byte
   preserved because both a unit test and `vllm-configuration.mdx` quote it.

5. **`components/src/dynamo/vllm/tests/test_vllm_unit.py`** — deleted the five
   tests that existed only to exercise the removed machinery
   (`test_connector_nixl_raises_error_with_migration_hint`,
   `test_connector_none_raises_error`, `test_env_var_dyn_connector_raises_error`,
   `test_connector_to_kv_transfer_json_single`,
   `test_connector_to_kv_transfer_json_multi`) plus the
   `_connector_to_kv_transfer_json` import.
   `test_prefill_worker_without_kv_transfer_config_raises` is kept — it matches on
   `--kv-transfer-config`, which survives the reword.

6. **`docs/fern/pages/reference/components/runtime-configuration.mdx`** —
   deleted the `<ParamField path="--connector">` block. The flag is no longer a
   universal runtime option, so documenting it on the shared runtime page would
   now be wrong.

7. **`docs/fern/pages/reference/backends/vllm-configuration.mdx`** — deleted
   only the "The earlier `--connector` flag is no longer accepted…" paragraph and
   its three bullets enumerating the removed `ValueError` variants. Everything
   PR #12568 added above it (the `--kv-transfer-config` guidance, the `<Warning>`,
   the bash example) is preserved verbatim.

8. **`recipes/nemotron-3-super-fp8/README.md`** — removed the stale
   "`--connector none` … rejected in 1.0" bullet from the Dynamo 0.9.1
   compatibility list.

9. **`recipes/nemotron-3-super-fp8/vllm/agg/deploy.yaml`** — removed the
   `--connector none` line from the header compatibility comment and the
   two-line inline note (plus its orphaned `#` separator) in the worker args.

## Why TRT-LLM's `--connector {none,kvbm}` is RETAINED, not deleted

**`--connector kvbm` is the live entry point for the KVBM TensorRT-LLM
integration and it is retained, merely re-homed from the shared runtime group
onto the TRT-LLM group.** Deleting it would remove the only way to enable that
integration. Concretely, `--connector kvbm` is read by `has_connector("kvbm")`,
which gates `build_kv_connector_config()` producing
`KvCacheConnectorConfig(connector_module="kvbm.trtllm_integration.connector", …)`;
`components/src/dynamo/trtllm/snapshot.py:191` also gates on
`config.has_connector("kvbm")`, and `tests/kvbm_integration/test_determinism_disagg.py:250`
passes `--connector` on the command line. None of that code was touched. The
task was to stop *every* backend inheriting a flag only TRT-LLM consumes — not
to remove the KVBM path.

## Why no new behavioural test is added on the vLLM side

Per `learnings/no-tautological-tests.md`: there is no surviving vLLM
`--connector` behaviour left to assert. The flag is simply not registered on the
vLLM parser anymore, so rejection is argparse's own `unrecognized arguments`
error, not Dynamo code. A test asserting "argparse rejects a flag we did not
define" would test argparse, not this repo. The five tests that covered the
deleted rejection machinery were removed with it; the correct evidence here is
the deletion plus the manual negative check recorded below, and the surviving
`test_prefill_worker_without_kv_transfer_config_raises`, which still covers the
real behaviour (prefill requires an explicit `--kv-transfer-config`).

## Safety constraints actually inspected

- **`docs/fern/assets/img/*.svg` — NOT modified.** Confirmed by inspection that
  those `--connector` hits are CSS custom properties for arrow colours
  (`--connector: #CBD5E1;`, `stroke="var(--connector)"`), unrelated to the CLI
  flag. `git status` shows no SVG in the changeset.
- **`docs/fern/pages/reference/general/releases/deprecations.mdx` — NOT
  modified.** It is the historical record of the #6450 removal and remains
  accurate; still shows its two `--connector` lines. Not in the changeset.
- **TRT-LLM KVBM path — intact.** `build_kv_connector_config`, `has_connector`,
  `VALID_TRTLLM_CONNECTORS`, `snapshot.py`, `components/src/dynamo/trtllm/tests/*`
  and `tests/kvbm_integration/test_determinism_disagg.py` are all unmodified.
- **`--kv-transfer-config`, `kv_connector*` literals,
  `dynamo.nixl_connect.Connector`, Rust files, planner connectors, multimodal
  media connectors — untouched.** `_uses_nixl_connector` and
  `_uses_dynamo_connector` in `vllm/args.py` were deliberately left alone. No
  `.rs` file is in the changeset (`lib/llm/src/block_manager/config.rs:213`
  mentions `--connector kvbm` in a comment and is correct as-is, since that flag
  still exists for TRT-LLM).
- **Formatting scoped to touched files only** (per `learnings/format-changed-only.md`).
- **Nothing pushed.**

### Blast-radius check

Grepped for other readers of the config field. Outside `components/src/dynamo/trtllm/`
there are no `config.connector` reads — the remaining `connector` hits are
unrelated locals (`aiohttp.TCPConnector`, omni stage connectors, multimodal cache
connectors, scheduler mocks). `common/snapshot/restore_context.py` and
`common/backend/worker.py` have no `connector` references, so removing the
annotation cannot break snapshot restore. `ConfigBase.from_cli_args` copies
argparse values by name onto a fresh instance and then materializes annotated
class defaults across the MRO, so dropping an annotation simply stops the field
being set — there is no positional coupling and no `KeyError`.

## What I ran, and what it said

All commands run from the repo checkout with `/opt/dynamo/venv/bin/python`.

| # | Command | Result |
|---|---|---|
| 1 | `ruff format <5 changed .py>` | 1 reformatted, 4 unchanged. **Superseded — see note below.** |
| 2 | `python -m py_compile <5 changed .py>` | PASS (silent) |
| 3 | TRT-LLM parse check (see below) | `--connector kvbm -> ['kvbm']`, unknown `[]` — **flag still parses** |
| 4 | Shared-runtime-only parse check | unknown `['--connector', 'nixl']`, `hasattr(ns,'connector') == False` — **flag gone from the shared group** |
| 5 | `python -m dynamo.vllm --help \| grep -c -- "--connector"` | `0` — not advertised by the vLLM backend |
| 6 | `python -m dynamo.vllm --model /tmp/nonexistent --connector nixl` | `error: unrecognized arguments: --connector nixl` — **rejected** |
| 7 | `pytest components/src/dynamo/vllm/tests/test_vllm_unit.py -q` | **117 passed** in 12.1 s |
| 8 | `pytest components/src/dynamo/common/tests/configuration -q` | **79 passed** |
| 9 | `pytest components/src/dynamo/common/tests/test_snapshot_restore_context.py -q` | **5 passed** |
| 10 | `pre-commit run --files <9 changed files>` | **black FAILED first pass** (reformatted `vllm/args.py`), then **all hooks PASS** on re-run |
| 11 | `py_compile` + `test_vllm_unit.py` re-run after black | PASS / **117 passed** |
| 12 | `git apply --check --reverse change.diff` | applies cleanly — the artefact matches the tree |

**Tried X, fell back to Y — honest notes:**

- **`ruff format` vs `black`.** I formatted with `ruff format` first (step 1).
  `pre-commit` then reported `black ... Failed - files were modified by this
  hook` and reformatted `components/src/dynamo/vllm/args.py`. Black — not ruff
  format — is this repo's canonical formatter. I re-ran the full hook set after
  black's rewrite and everything passed, then re-ran `py_compile` and the vLLM
  unit tests on the black-formatted file. The committed tree is black-clean.
  The only files ruff/black touched are the ones I edited.

- **TRT-LLM `--help` could not be run.** `tensorrt_llm` is **not installed** in
  `/opt/dynamo/venv`, so `python -m dynamo.trtllm --help` fails at import with
  `ModuleNotFoundError: No module named 'tensorrt_llm'`. I fell back to importing
  the arg groups directly with a minimal `tensorrt_llm.llmapi.BuildConfig` stub
  (only `model_fields` is consulted at registration time) and parsing through
  argparse:

  ```
  TRTLLM  --connector kvbm -> ['kvbm'] | unknown: []
  runtime --connector nixl -> unknown: ['--connector', 'nixl'] | has attr: False
  ```

  This is the same code path `parse_args` uses, so it is a real check of the
  registration, but it is not a full end-to-end `--help` and the validator should
  redo it in an image that actually has TensorRT-LLM.

- **TRT-LLM unit tests could not be run**, for the same reason:
  `pytest components/src/dynamo/trtllm/tests/` errors during collection with
  `ModuleNotFoundError: No module named 'tensorrt_llm'`. **I verified this is
  pre-existing** by stashing my changes and re-running — identical collection
  error on clean `main`. These tests (which assert
  `parse_args(["--connector","none"])` and `["--connector","kvbm"])` succeed, and
  that two values raise) are the most important remaining evidence for the
  re-homing, and **the validator must run them in a TRT-LLM image.**

- **`pytest components/src/dynamo/common/` (whole tree) core-dumps** partway
  through, inside `tests/multimodal/test_embedding_transfer.py` (NIXL/GPU
  transfer tests in a GPU-less sandbox). **Verified pre-existing** by stashing and
  re-running on clean `main` — same core dump. I fell back to running the two
  relevant subsets (steps 8 and 9), which pass.

- **`tests/kvbm_integration/test_determinism_disagg.py` was not run** — it needs
  GPUs and a KVBM-capable image. It is unmodified; it passes `--connector` to a
  TRT-LLM worker, which still accepts it.

## Notes for the validator

1. **Highest-value check I could not perform:** `pytest
   components/src/dynamo/trtllm/tests/test_trtllm_unit.py` (and
   `test_trtllm_snapshot.py`) in an image with `tensorrt_llm` installed. Those
   tests directly assert the re-homed flag parses and validates. My stub-based
   parse check is a proxy, not a substitute.
2. Two pre-existing sandbox failures are **not** caused by this change and both
   were confirmed against a stashed clean tree: the `tensorrt_llm` import error,
   and the `common/tests/multimodal/test_embedding_transfer.py` core dump.
3. The vLLM negative check is now argparse-level, so recipe 07 (agg smoke) is the
   real regression signal for the vLLM path: any deployment still passing
   `--connector` will now fail with `unrecognized arguments` rather than a Dynamo
   `ValueError`. That change in error *shape* (not outcome) is intentional and is
   the main user-visible consequence of the diff.
4. `docs/fern/pages/reference/general/releases/deprecations.mdx` still documents
   the #6450 removal and still contains the string `--connector`. That is correct
   and deliberate — do not flag it as a missed edit.
5. The `--connector` matches remaining in `docs/fern/assets/img/*.svg` are CSS
   variables for diagram arrow colours, not the CLI flag. Also deliberate.

MR URL: https://github.com/ai-dynamo/dynamo/pull/12611

# Change validation — remove deprecated `--connector` from the shared runtime group

Work item `wi-20260803T205823Z-12568`, branch `06a1058ba`. The change deletes the
deprecated `--connector` flag from the shared runtime arg group and re-homes an
equivalent flag onto the TRT-LLM backend, where it is still meaningful. Diff is
9 files, +10/−169.

All five recipes nominated by the plan ran green on the printer's branch. Nothing
carries a disposition. The generated evidence table below is the authority for
what actually executed; this prose is narration around it.

## What the change actually does

Three edits carry the behaviour, the rest are follow-on cleanup:

1. `components/src/dynamo/common/configuration/groups/runtime_args.py` drops both
   the `connector: list[str]` annotation on `DynamoRuntimeConfig` and the
   `add_argument(...)` block that registered `--connector` / `DYN_CONNECTOR`.
   After this, no backend inherits the flag from the shared group.
2. `components/src/dynamo/trtllm/backend_args.py` adds the equivalent flag back
   on the TRT-LLM config, with help text scoped to the TensorRT-LLM engine.
3. `components/src/dynamo/vllm/args.py` deletes `_reject_connector_flag()` and
   `_connector_to_kv_transfer_json()`, their call site, the `connector = []`
   reset, and the now-unused `import json`.

The consequence worth validating is a **change in who rejects the flag**. Before,
vLLM accepted `--connector` at the parser and then raised a Dynamo `ValueError`
explaining it was unsupported. Now the parser itself has never heard of it, so
rejection comes from argparse. Both reject; the error surface differs. That is
the substance of the negative check below.

## Recipe 07 — the aggregate smoke, in three parts

Run on the local A100-SXM4-80GB with in-sandbox vLLM 0.22.0, real Qwen3-0.6B
weights, `--enforce-eager`, frontend and worker as plain processes over the file
discovery backend. All three parts passed, and the whole recipe was reproduced
green twice.

**Positive.** `python -m dynamo.vllm` starts, registers three endpoints
(`generate`, `clear_kv_blocks`, `get_perf_metrics`) with `device_type: cuda`,
appears in `/v1/models` as `Qwen/Qwen3-0.6B`, and answers a chat completion with
**HTTP 200** and real content (`'<think>\nOkay, the'`, 5 completion tokens,
`finish_reason: length`). This is a genuine served completion, not a health probe.

**Negative.** `python -m dynamo.vllm --model Qwen/Qwen3-0.6B --connector nixl`
exits **2**. Exact final stderr line:

```
__main__.py: error: unrecognized arguments: --connector nixl
```

Two supporting facts make this a removal proof rather than a coincidence:
`--connector` occurs **0 times** in `python -m dynamo.vllm --help`, and the old
Dynamo message (`no longer supported for the vLLM backend`) is absent from
stderr. Rejection is argparse's now, exactly as intended.

**Collateral check for PR #12568.** The documented replacement path works. A
worker launched with
`--kv-transfer-config '{"kv_connector":"NixlConnector","kv_role":"kv_both"}'`
reaches the same healthy serving state — registers, appears in `/v1/models`,
returns HTTP 200 with content — with zero argparse or `ValueError` rejections in
its log, and NIXL genuinely engaged (`NIXL is available`, side-channel host
auto-detected). GPU returned to 1 MiB after teardown; no leak.

### Two earlier red 07 rows, and why they are mine and not the change's

The registry shows two failed 07 attempts before the green ones. Both were
defects in my own driver script. I recorded a separate probe establishing this
rather than leaving unexplained red rows.

The first used `--store-kv file`, taken from the recipe text. That flag does not
exist in this build — it occurs 0 times in `--help`; the current equivalent is
`--discovery-backend {kubernetes,etcd,file,mem}`. Both processes died on
argparse before touching the change.

The second had a wrong readiness gate. I polled `/health`, which reports
`{"status":"healthy","endpoints":[],"instances":[]}` the moment the *frontend*
binds its HTTP service — before any worker registers. My loop broke at ~10s and
tore down a worker that was still loading. A foreground run showed the worker
needs ~60s to register (engine init alone is 14.2s) and does register correctly.
Gating on `/v1/models` instead makes the recipe green. No red 07 row is
attributable to the `--connector` removal.

## Recipe 03 — unit tests

Scoped to what is reachable in this vLLM image, with the unreachable set
accounted for rather than quietly dropped. Results: vLLM unit **117 passed**;
shared configuration + snapshot-restore **84 passed**; TRT-LLM test directory
**46 passed, 1 skipped**; SGLang test directory **45 passed, 10 deselected**.

Beyond the suites, three runtime assertions prove the removal directly:
`DynamoRuntimeConfig.__annotations__` no longer contains `connector`; feeding
`--connector nixl` to a parser built from `DynamoRuntimeArgGroup` returns it in
`unknown` with `hasattr(ns, "connector") == False`; and the prefill guard test
`test_prefill_worker_without_kv_transfer_config_raises` **passes**, confirming
that the reworded `ValueError` for `--disaggregation-mode prefill` without
`--kv-transfer-config` still fires. The reword removed only the stale
`--connector` sentence; the rest of the message is preserved verbatim.

### The printer's caveat, verified independently

I did not take the printer's environment note on trust.

`tensorrt_llm` is genuinely not installed in `/opt/dynamo/venv`, and this is
pre-existing. Directory-level TRT-LLM collection succeeds only because
`components/src/dynamo/trtllm/tests/conftest.py` has a `pytest_ignore_collect`
hook that skips `test_trtllm_*.py` when `importlib.util.find_spec("tensorrt_llm")`
is None; naming those files explicitly produces a collection
`ModuleNotFoundError: No module named 'tensorrt_llm'`. Non-causation is
structural: the `tensorrt_llm` import block is byte-identical between `HEAD~1`
and `HEAD`, and the diff neither adds nor removes a `tensorrt_llm` import.
`components/src/dynamo/sglang/tests/conftest.py` gates the same way on `sglang`,
and `git diff --name-only HEAD~1 HEAD` touches no SGLang file at all. The omni
tests skip at module level on `No module named 'vllm_omni'`.

I did not confirm the `components/src/dynamo/common/` core-dump caveat, because I
scoped Recipe 03 to the specific config and snapshot targets rather than the whole
directory, so `test_embedding_transfer.py` never ran. That is a deliberate
scoping choice, not a silent pass — it is called out here so the caveat is not
recorded as verified when it was merely avoided.

## Recipes 00, 01, 04

Recipe 00 ran `dynamo-prepare-python-validation` against the checkout and
confirmed `dynamo` and `dynamo._core` both import from it — the prerequisite for
everything else here. Recipe 01 covers `py_compile` on the five changed Python
files plus `pre-commit` over all nine changed files including the four docs and
recipe files. Recipe 04 adds a dead-import sweep specific to this change:
`ruff F401,F811,F821` on the four touched runtime modules, confirmation that the
now-unused `import json` was actually removed from `vllm/args.py`, and a
tree-wide grep proving **zero** remaining references to either deleted helper.
Recipe 04's first attempt failed only because I invoked `python -m ruff`; ruff is
a standalone binary, and the corrected invocation is green.

## Assessment

The removal is clean and complete. The flag is gone from the shared group at both
the config-annotation and parser levels, gone from vLLM's help output, and its
dead helper code left no dangling references. The replacement path
(`--kv-transfer-config`) serves real traffic on real hardware, so users following
the updated docs land somewhere that works. The re-homed TRT-LLM flag could not be
exercised at runtime here because `tensorrt_llm` is absent from this image — that
is an environment limit, verified as pre-existing and unrelated to the change, and
the TRT-LLM arg-parsing tests that *are* reachable pass.

The one thing a reviewer should weigh, since no test can decide it, is the
user-facing consequence of the changed rejection surface: an operator who passes
`--connector` to vLLM now gets argparse's terse `unrecognized arguments` instead
of the previous message that explained the migration. The docs changes in this
diff cover it, but the runtime no longer does.

## Verdict: pass

> 🤖 **Automated AI review — advisory.** An AI agent's judgment of
> whether this change is logically sound on the evidence; not a merge
> authorization. CI, customs, and a human reviewer hold that.

## Assessment: sound

Nine files, +10/−169, on branch `docs/remove-connector-flag--bb15f14dece7` at
`06a1058ba6d9d979f0fc779ce436ec4aa9afa508` (matches `change.md`; working tree
clean). The deprecated `--connector` flag is removed from the shared runtime arg
group, re-homed onto the TRT-LLM backend where it is still live, and the vLLM
rejection scaffolding it existed to serve is deleted. Evidence table is
`5/5 validated`, `customs: cleared`. Two nits, no blocking findings.

## Findings

| # | Location | Severity | Claim | Evidence |
|---|---|---|---|---|
| 1 | `docs/fern/pages/reference/backends/tensorrt-llm-configuration.mdx:143` | nit | The flag re-homed to TRT-LLM at `components/src/dynamo/trtllm/backend_args.py:110` is now documented nowhere. The diff correctly deletes `--connector` from the shared runtime reference (`runtime-configuration.mdx`) and from the vLLM page, but adds no `ParamField` to the TRT-LLM page. Consequence: an operator who wants KVBM on TRT-LLM can no longer discover the flag from the docs site — only from `--help` or the source. | `grep -rn -- "--connector" docs/fern/pages/reference/backends/` returns nothing at HEAD. The page carries 96 `ParamField` entries and a `## KV cache and events` section at line 143 that is the natural home. Graded nit, not blocking: `plan.md:317` made this explicitly discretionary ("If the printer judges that TRT-LLM's flag deserves a home in the docs, add it… but do not leave it advertised as a universal runtime option"). The binding half of that instruction — do not leave it advertised as universal — is satisfied. |
| 2 | `validation/logs/2026-08-03T22-56-14.319Z-bash-f473.log:73` | nit | Prose/log discrepancy. `change-validation.md:63` asserts "GPU returned to 1 MiB after teardown; no leak," but the log's own final "leak check" line reads `0, 75419 MiB`. Consequence: read literally, the cited log contradicts the narration at the one point where the narration makes a resource claim. | The claim is nonetheless true — the log line is a race in the driver script: `nvidia-smi` was sampled immediately after `kill` on line 71, before the CUDA context was released. I re-sampled independently at review time: `nvidia-smi --query-gpu=index,memory.used` → `0, 1 MiB`. Line 42 of the same log shows the *positive* worker's teardown correctly draining to `0, 1 MiB`, so only the last of the two teardowns was mis-sampled. Nit for log hygiene only; no leak, and no bearing on the change. |

## Do-not-touch compliance — verified independently

Checked against the tree and `git diff HEAD~1 HEAD`, not against `change.md`'s
account. `git diff --name-only HEAD~1 HEAD` yields exactly the nine paths the
plan named, and the forbidden-path scan over that list returns zero for `.svg`,
`deprecations.mdx`, `.rs`, `snapshot.py`, `kvbm`, `planner`, and `multimodal`.

- **SVGs / CSS `--connector:` custom properties** — 0 `.svg` files in the diff.
- **`deprecations.mdx`** — untouched; lines 237 and 239 still carry the
  `Removed` badge, the #6450 link, and the full **Migrate:** line mapping
  `--connector nixl` → `--kv-transfer-config '{"kv_connector":"NixlConnector","kv_role":"kv_both"}'`.
- **`kv_connector*` literals** — present in the diff only as deletions *inside*
  the removed `_connector_to_kv_transfer_json` helper and its two deleted tests.
  No live literal changed. `kv_connector_protocols.py`, `vllm/main.py`,
  `vllm/handlers.py` spot-checked UNCHANGED.
- **`dynamo.nixl_connect.Connector`** — untouched. `_uses_nixl_connector`
  (`components/src/dynamo/vllm/args.py:423`) and `_uses_dynamo_connector`
  (`:445`) both survive intact.
- **TRT-LLM KVBM path** — `build_kv_connector_config`, `has_connector`,
  `snapshot.py`, `workers/llm_worker.py`, `request_handlers/handler_base.py`,
  and `tests/kvbm_integration/test_determinism_disagg.py` all UNCHANGED;
  `git diff --stat HEAD~1 HEAD -- components/src/dynamo/trtllm/tests/` is empty.
- **Rust** — 0 `.rs` files; `lib/llm/src/block_manager/config.rs` UNCHANGED.
- **Planner / multimodal connectors** — 0 files.

## Scope vs. the plan — the mypy redeclaration

The printer deleted `connector: list[str]  # Redeclare for mypy (inherited from
DynamoRuntimeConfig)` from `components/src/dynamo/trtllm/args.py`. This is
**within latitude and correct.**

Within latitude: `plan.md:288-290` grants exactly this discretion — "either
loses its stale comment or is dropped once the field is declared on
`DynamoTrtllmConfig`; printer's judgment, as long as mypy stays clean." The
field *was* declared on `DynamoTrtllmConfig` in the same diff
(`components/src/dynamo/trtllm/backend_args.py:502`), so the precondition holds.

Correct: `Config(DynamoRuntimeConfig, DynamoTrtllmConfig)` still resolves the
annotation — `typing.get_type_hints` on `Config` gives `connector -> list[str]`,
`Config.__annotations__` no longer owns it, and the provider is
`DynamoTrtllmConfig`. `ConfigBase.from_cli_args` copies argparse values by name
and then materializes annotated class defaults across the MRO, so nothing is
positionally coupled and a vanished annotation raises no `KeyError`. The
`validate()` connector block, `VALID_TRTLLM_CONNECTORS`, and `has_connector()`
in `trtllm/args.py` are untouched and still see the field.

mypy stays clean under CI's actual invocation. A single-file
`mypy components/src/dynamo/trtllm/args.py` reports spurious
`Cannot determine type of "connector" [has-type]` — that is an artifact of
invoking mypy without the package context, not a defect. Reproducing CI's shape
from `.github/workflows/dynamo-pipeline.yml:193-198`
(`MYPYPATH=components/src:lib/bindings/python/src mypy --explicit-package-bases <dirs>`)
over `components/src/dynamo/trtllm` gives `Success: no issues found in 72 source
files`. The same invocation over `vllm` + `common` surfaces 3 errors, all
pre-existing at `HEAD~1` and unrelated to this change.

## Evidence table — audited row by row

`## Evidence [5/5 validated]`, `customs: cleared [5/5 validated]`. Every recipe
the plan nominated (00, 01, 03, 04, 07) is present and `validated`. No `missing`
row. Each cited log shows real execution:

- **00** — `dynamo-prepare-python-validation` against this checkout, then
  `import dynamo, dynamo._core` both resolving from it. The change was built.
- **01** — `py_compile` on the five changed `.py` files, then `pre-commit` over
  all nine changed files including docs and recipe YAML.
- **03** — vLLM unit **117 passed**; shared configuration + snapshot-restore
  **84 passed**; TRT-LLM dir **46 passed, 1 skipped**; SGLang dir **45 passed,
  10 deselected**; plus three runtime assertions that prove the removal directly
  (`connector` absent from `DynamoRuntimeConfig.__annotations__`; a parser built
  from `DynamoRuntimeArgGroup` returns `--connector nixl` in `unknown` with
  `hasattr(ns, "connector") == False`).
- **04** — `pre-commit` + `ruff F401,F811,F821` on the four touched runtime
  modules, `import json` confirmed removed, tree-wide grep proving zero
  surviving references to either deleted helper.
- **07** — real A100-SXM4-80GB, real Qwen3-0.6B weights, three parts all green.

### The red→green story, checked against the logs

The important question is whether any green row is green because the harness was
loosened. It is not — in the one case where the gate changed, it was
**tightened.**

- **04** red (exit 1) failed on `No module named ruff` — the validator invoked
  `python -m ruff` for a standalone binary. Green run calls
  `/usr/local/bin/ruff`. Same checks, working invocation.
- **03** red rows are `ModuleNotFoundError: No module named 'sglang'`
  (collection abort, exit 2) then 12 `No module named 'sglang.srt'` failures.
  The green run deselects/ignores exactly those engine-gated tests, in files
  that `git diff --name-only HEAD~1 HEAD` shows are not in the changeset. The
  change is not implicated and nothing in the changeset was excluded.
- **07** red attempt 1 used `--store-kv file` from the recipe text; that flag
  does not exist in this build (`--store-kv occurrences in vllm --help: 0`; the
  real flag is `--discovery-backend {kubernetes,etcd,file,mem}`). Both processes
  died at argparse before reaching the change.
- **07** red attempt 2 gated readiness on `/health`, which returns
  `{"status":"healthy","endpoints":[],"instances":[]}` the moment the *frontend*
  binds — before any worker registers. The loop broke at ~10 s and killed a
  still-loading worker.

  The replacement gate is **stronger than the recipe's own**: recipe
  `07-agg-smoke.md` prescribes waiting on `/health` returning `"status"`; the
  validator instead waits for the worker to appear in `/v1/models`
  (`Worker REGISTERED at attempt 12 (~60s)`). The recipe's actual pass
  conditions — HTTP 200 with `choices[0].message.content`, card back at baseline
  — were not relaxed and were genuinely met: `HTTP 200`,
  `content: '<think>\nOkay, the'`, 5 completion tokens,
  `finish_reason: length`, three endpoints registered with `device_type: cuda`.
  No red 07 row is attributable to the `--connector` removal.

## Substance behind the verdict

`## Verdict: pass`, unqualified. This is not a hedged verdict papering over
unbuilt or unrun work: recipe 00 imported the built artifact, and recipe 07
served real traffic from real weights on a real A100. The validation stands on
execution, not on assertion.

## Ruling on the escalated claim — the changed rejection surface

**Acceptable.** An operator who passes `--connector` to vLLM now gets argparse's
`unrecognized arguments: --connector nixl` (exit 2) instead of the Dynamo
`ValueError` that explained the migration. Reasoning:

1. **The flag is already gone**, removed in #6450 and merged. What this diff
   deletes is not the flag but the vestigial rejection scaffolding left behind
   after it — which is precisely what the work item asked for. Keeping bespoke
   rejection code indefinitely for a flag removed releases ago is the
   accumulation the removal was meant to reverse.
2. **The migration text has a durable home.** `deprecations.mdx:237,239` retains
   the `Removed` badge, the PR link, and the exact before/after mapping. That
   ledger, not a runtime error string, is where a user hitting a removed flag is
   directed.
3. **This diff fixes the places that were still telling users to pass it** —
   `vllm-configuration.mdx`, `runtime-configuration.mdx`,
   `recipes/nemotron-3-super-fp8/README.md`, and the recipe `deploy.yaml`. The
   population that would have hit the old `ValueError` was largely people
   following those files.
4. **The actionable guard survives.** The `ValueError` for
   `--disaggregation-mode prefill` without `--kv-transfer-config` is preserved
   verbatim minus the stale `--connector` sentence, and
   `test_prefill_worker_without_kv_transfer_config_raises` passes green in
   recipe 03. The message that tells a user what to *do* is intact; only the
   message about a flag that no longer exists is gone.
5. **The failure mode is loud, not silent.** Exit 2 with the offending token
   echoed is unambiguous. The genuinely bad outcome — accepting `--connector`
   and ignoring it — is not what happens here.

The trade is a slightly terser error for a flag that was removed a release ago,
in exchange for ~140 lines of dead scaffolding. That is the right side of the
trade.

## Coverage honesty — the TRT-LLM re-homing

**Adequate, and honestly reported.** `tensorrt_llm` is absent from
`/opt/dynamo/venv`, so the re-homed flag could not be exercised at runtime. The
validator did not paper over this; it argued non-causation structurally, and the
argument is verifiable:

- `components/src/dynamo/trtllm/tests/conftest.py:15-23` has a
  `pytest_ignore_collect` hook returning `True` for `test_trtllm_*.py` when
  `importlib.util.find_spec("tensorrt_llm") is None` — so directory-level
  collection succeeding is explained by the gate, not by the change.
- The `tensorrt_llm` import block is byte-identical between `HEAD~1` and `HEAD`,
  and the diff neither adds nor removes a `tensorrt_llm` import.
- `git diff --stat HEAD~1 HEAD -- components/src/dynamo/trtllm/tests/` is empty.
- The environment limit is pre-existing: the printer confirmed it by stashing.

The parse-time surface that *is* reachable did run: 46 TRT-LLM tests passed, and
the annotation resolution through `DynamoTrtllmConfig` is confirmed both by
`get_type_hints` and by CI-shaped mypy. What remains unexercised is the runtime
KVBM path, which this diff does not touch.

The validator was also honest about the one caveat it did not check:
`change-validation.md:116-120` states plainly that it did **not** confirm the
printer's `components/src/dynamo/common/` core-dump caveat, because recipe 03
was scoped to specific config and snapshot targets so `test_embedding_transfer.py`
never ran — "called out here so the caveat is not recorded as verified when it
was merely avoided." That is the correct disclosure, and it does not touch the
changeset (no multimodal file is in the diff).

## New test infrastructure

None added. The change deletes five vLLM unit tests that exercised the removed
helpers and adds no fixture, helper, or parametrised harness. The
"registration is not exercise" check is satisfied vacuously.